home *** CD-ROM | disk | FTP | other *** search
/ Merciful 1 / Merciful - Disc 1.iso / software / a / asm_one / asm-onev1.25a.dms / in.adf / Release3.1 / AutoDocs3.1.lha / doc / serial.doc < prev    next >
Encoding:
Text File  |  1993-08-12  |  21.4 KB  |  584 lines
  1.  
  2.  
  3. TABLE OF CONTENTS
  4.  
  5. serial.device/AbortIO
  6. serial.device/BeginIO
  7. serial.device/CloseDevice
  8. serial.device/CMD_CLEAR
  9. serial.device/CMD_FLUSH
  10. serial.device/CMD_READ
  11. serial.device/CMD_RESET
  12. serial.device/CMD_START
  13. serial.device/CMD_STOP
  14. serial.device/CMD_WRITE
  15. serial.device/OpenDevice
  16. serial.device/SDCMD_BREAK
  17. serial.device/SDCMD_QUERY
  18. serial.device/SDCMD_SETPARAMS
  19.  
  20.  
  21. serial.device/AbortIO                                     serial.device/AbortIO
  22.  
  23.    NAME
  24.        AbortIO(ioRequest) -- abort an I/O request
  25.                A1
  26.  
  27.    FUNCTION
  28.       This is an exec.library call.
  29.  
  30.       This function attempts to aborts a specified read or write request.
  31.       If the request is active, it is stopped immediately. If the request is
  32.       queued, it is painlessly removed.  The request will be returned
  33.       in the same way any completed request it.
  34.  
  35.       After AbortIO(), you must generally do a WaitIO().
  36.  
  37.    INPUTS
  38.       iORequest  -- pointer to the IORequest Block that is to be aborted.
  39.  
  40.    RESULTS
  41.        io_Error -- if the Abort succeded, then io_Error will be #IOERR_ABORTED
  42.  
  43.            (-2) and the request will be flagged as aborted (bit 5 of 
  44.            io_Flags is set).  If the Abort failed, then the Error will be zero.
  45.  
  46.    BUGS
  47.        Previous to version 34, the serial.device would often hang when
  48.        aborting CTS/RTS handshake requests.  This was the cause of the
  49.        incorrect assumption that AbortIO() does not need to be followed
  50.        by a wait for a reply (or a WaitIO()). 
  51.  
  52.  
  53. serial.device/BeginIO                                     serial.device/BeginIO
  54.  
  55.    NAME
  56.        BeginIO(ioRequest),deviceNode -- start up an I/O process
  57.                 A1        A6
  58.    FUNCTION
  59.        This is a direct function call to the device.  It is intended for
  60.        more advanced programmers.  See exec's DoIO() and SendIO() for
  61.        the normal method of calling devices.
  62.  
  63.        This function initiates a I/O request made to the serial
  64.        device. Other than read or write, the functions are performed 
  65.        synchronously, and do not depend on any interrupt handling 
  66.        logic (or it's associated discontinuities), and hence should
  67.        be performed as IO_QUICK.
  68.        With some exceptions, reads and writes are merely initiated by 
  69.        BeginIO, and thusly return to the caller as begun, not completed.
  70.        Completion is signalled via the standard ReplyMsg routine.
  71.        Multiple requests are handled via FIFO queueing.
  72.        One exception to this non-QUICK handling of reads and writes
  73.        is for READS when:
  74.          - IO_QUICK bit is set
  75.          - There are no pending read requests
  76.          - There is already enough data in the input buffer to satisfy
  77.            this I/O Request immediately.
  78.        In this case, the IO_QUICK flag is not cleared, and the request
  79.        is completed by the time it returns to the caller. There is no
  80.        ReplyMsg or signal bit activity in this case.
  81.           
  82.    INPUTS
  83.        ioRequest  -- pointer to an I/O Request Block of size 
  84.            io_ExtSerSize (see serial.i for size/definition), 
  85.            containing a valid command in io_Command to process,
  86.            as well as the command's other required parameters.
  87.        deviceNode -- pointer to the "serial.device", as found in
  88.            the IO_DEVICE of the ioRequest.
  89.  
  90.    RESULTS
  91.        io_Error -- if the BeginIO succeded, then Error will be null.
  92.            If the BeginIO failed, then the Error will be non-zero.
  93.            I/O errors won't be reported until the io completes.
  94.  
  95.    SEE ALSO
  96.     devices/serial.h
  97.  
  98.  
  99. serial.device/CloseDevice                             serial.device/CloseDevice
  100.  
  101.    NAME
  102.        CloseDevice -- close the serial port
  103.  
  104.    SYNOPSIS
  105.        CloseDevice(deviceNode)
  106.                     A1
  107.    FUNCTION
  108.        This is an exec call that terminates communication with the
  109.        serial device.  Upon closing, the device's input buffer is freed.
  110.  
  111.        Note that all IORequests MUST be complete before closing.
  112.     If any are pending, your program must AbortIO() then WaitIO()
  113.        to complete them.
  114.  
  115.    INPUTS
  116.        deviceNode - pointer to the device node, set by Open
  117.  
  118.    SEE ALSO
  119.        serial.device/OpenDevice
  120.  
  121.  
  122. serial.device/CMD_CLEAR                                 serial.device/CMD_CLEAR
  123.  
  124.    NAME
  125.        Clear -- clear the serial port buffers
  126.  
  127.    FUNCTION
  128.        This command resets the serial port's read buffer pointers.
  129.  
  130.    IO REQUEST
  131.        io_Message      mn_ReplyPort initialized
  132.        io_Device       set by OpenDevice
  133.        io_Unit         set by OpenDevice
  134.        io_Command      CMD_CLEAR
  135.  
  136.    RESULTS
  137.        Error -- If the Clear succeded, then io_Error will be null.
  138.                 If the Clear failed, then the io_Error will be non-zero.
  139.  
  140.  
  141. serial.device/CMD_FLUSH                                 serial.device/CMD_FLUSH
  142.  
  143.    NAME
  144.        Flush -- clear all queued I/O requests for the serial port
  145.  
  146.    FUNCTION
  147.        This command purges the read and write request queues for the
  148.        serial device. Flush will not affect active requests.
  149.  
  150.    IO REQUEST
  151.        io_Message      mn_ReplyPort initialized
  152.        io_Device       set by OpenDevice
  153.        io_Unit         set by OpenDevice
  154.        io_Command      CMD_FLUSH
  155.  
  156.    RESULTS
  157.        Error -- if the Flush succeded, then io_Error will be null.
  158.                 If the Flush failed, then the io_Error will be non-zero.
  159.  
  160.  
  161. serial.device/CMD_READ                                   serial.device/CMD_READ
  162.  
  163.    NAME
  164.        Read -- read input from serial port
  165.  
  166.    FUNCTION
  167.     This command causes a stream of characters to be read in from
  168.     the serial port buffer.  The number of characters is specified
  169.     in io_Length.
  170.  
  171.     The Query function can be used to check how many characters
  172.     are currently waiting in the serial port buffer.  If more characters
  173.     are requested than are currently available, the ioRequest
  174.     will be queued until it can be satisfied.
  175.  
  176.  
  177.     The best way to handle reads is to first Query to get the number
  178.     of characters currently in the buffer.  Then post a read request
  179.     for that number of characters (or the maximum size of your buffer).
  180.  
  181.     If zero characters are in the buffer, post a request
  182.     for 1 character.  When at least one is ready, the device will return
  183.     it.  Now start over with another Query.
  184.  
  185.     Before the program exits, it must be sure to AbortIO() then WaitIO()
  186.     any outstanding ioRequests.
  187.  
  188.    IO REQUEST
  189.        io_Message      A mn_ReplyPort is required
  190.        io_Device       set by OpenDevice
  191.        io_Unit         set by OpenDevice
  192.        io_Command      CMD_READ
  193.        io_Flags        If the IOB_QUICK bit is set, read will try
  194.             to complete the IO quickly
  195.        io_Length       number of characters to receive.
  196.        io_Data         pointer to buffer
  197.  
  198.    RESULTS
  199.        Error -- if the Read succeded, then io_Error will be null.
  200.            If the Read failed, then io_Error will be non-zero.
  201.          io_Error will indicate problems such as parity mismatch,
  202.          break, and buffer overrun.
  203.  
  204.    SEE ALSO
  205.     serial.device/SDCMD_QUERY
  206.     serial.device/SDCMD_SETPARAMS
  207.  
  208.    BUGS
  209.     Having multiple outstanding read IORequests at any one time will
  210.     probably fail.
  211.  
  212.     Old documentation mentioned a mode where io_Length was set to -1.
  213.     If you want a NULL terminated read, use the io_TermArray instead.
  214.  
  215.  
  216. serial.device/CMD_RESET                                 serial.device/CMD_RESET
  217.  
  218.    NAME
  219.        Reset -- reinitializes the serial port
  220.  
  221.    FUNCTION
  222.        This command resets the serial port to its freshly initialized
  223.        condition. It aborts all I/O requests both queued and current,
  224.        relinquishes the current buffer, obtains a new default sized
  225.        buffer, and sets the port's flags and parameters to their 
  226.        boot-up time default values. The functions places the reset
  227.        parameter values in the ioRequest block.
  228.  
  229.    IO REQUEST
  230.        io_Message      mn_ReplyPort initialized
  231.        io_Device       set by OpenDevice
  232.        io_Unit         set by OpenDevice
  233.        io_Command      CMD_RESET
  234.  
  235.    RESULTS
  236.        Error -- if the Reset succeded, then Error will be null.
  237.            If the Reset failed, then the Error will be non-zero.
  238.  
  239.  
  240. serial.device/CMD_START                                 serial.device/CMD_START
  241.  
  242.    NAME
  243.        Start -- restart paused I/O over the serial port
  244.  
  245.    FUNCTION
  246.        This function restarts all current I/O on the serial port by 
  247.        sending an xON to the "other side", and submitting a "logical
  248.        xON" to "our side", if/when appropriate to current activity.
  249.  
  250.    IO REQUEST
  251.        io_Message      mn_ReplyPort initialized
  252.        io_Device       set by OpenDevice
  253.        io_Unit         set by OpenDevice
  254.        io_Command      CMD_START
  255.  
  256.    RESULTS
  257.  
  258.    SEE ALSO
  259.        serial.device/CMD_STOP
  260.  
  261.  
  262. serial.device/CMD_STOP                                   serial.device/CMD_STOP
  263.  
  264.    NAME
  265.        Stop -- pause all current I/O over the serial port
  266.  
  267.    FUNCTION
  268.        This command halts all current I/O on the serial port by 
  269.        sending an xOFF to the "other side", and submitting a "logical
  270.        xOFF" to "our side", if/when appropriate to current activity.
  271.  
  272.    IO REQUEST
  273.        io_Message      mn_ReplyPort initialized
  274.        io_Device       set by OpenDevice
  275.        io_Unit         set by OpenDevice
  276.        io_Command      CMD_STOP
  277.  
  278.    RESULTS
  279.  
  280.    SEE ALSO
  281.        serial.device/CMD_START
  282.  
  283.  
  284. serial.device/CMD_WRITE                                 serial.device/CMD_WRITE
  285.  
  286.    NAME
  287.        Write -- send output to serial port
  288.  
  289.    FUNCTION
  290.        This command causes a stream of characters to be written out
  291.        the serial port. The number of characters is specified in
  292.        io_Length, unless -1 is used, in which case output is sent until
  293.        a null(0x00) is encountered. 
  294.  
  295.    IO REQUEST
  296.        io_Message      must have mn_ReplyPort initialized
  297.        io_Device       set by OpenDevice
  298.        io_Unit         set by OpenDevice
  299.        io_Command      CMD_WRITE
  300.        io_Flags        Set IOF_QUICK to try quick I/O
  301.        io_Length       number of characters to transmit, or if set
  302.                        to -1 transmit until null encountered in buffer
  303.        io_Data         pointer to block of data to transmit
  304.  
  305.    RESULTS
  306.        Error -- if the Write succeded, then io_Error will be null.
  307.            If the Write failed, then the io_Error will be non-zero.
  308.  
  309.    SEE ALSO
  310.     serial.device/SDCMD_SETPARAMS
  311.  
  312.  
  313. serial.device/OpenDevice                               serial.device/OpenDevice
  314.  
  315.    NAME
  316.        OpenDevice -- Request an opening of the serial device.
  317.  
  318.    SYNOPSIS
  319.        error = OpenDevice("serial.device", unit, ioRequest, flags)
  320.        D0                  A0              D0    A1         D1
  321.  
  322.     BYTE OpenDevice(STRPTR, ULONG, struct IOExtSer *, ULONG);
  323.  
  324.    FUNCTION
  325.        This is an exec call.  Exec will search for the serial.device, and
  326.        if found, will pass this call on to the device.
  327.  
  328.        Unless the shared-access bit (bit 5 of io_SerFlags) is set, 
  329.        exclusive use is granted and no other access to that unit is
  330.        allowed until the owner closes it.  All the serial-specific fields
  331.        in the ioRequest are initialized to their most recent values (or
  332.        the Preferences default, for the first time open).
  333.  
  334.        If support of 7-wire handshaking (i.e. RS232-C CTS/RTS protocol)
  335.        is required, use the serial.device/SDCMD_SETPARAMS command.
  336.     This feature should also be specified at inital OpenDevice() time.
  337.  
  338.    INPUTS
  339.        "serial.device"    - pointer to literal string "serial.device"
  340.        unit          - Must be zero, or a user setable unit number.
  341.               (This field is used by multiple port controllers)
  342.                          Zero specifies the default serial port.
  343.        ioRequest     - pointer to an ioRequest block of size io_ExtSerSize
  344.                          to be initialized by the serial.device.
  345.                          (see devices/serial.h for the definition)
  346.                            NOTE use of io_SerFlags (see FUNCTION above)
  347.         IMPORTANT: The ioRequest block MUST be of size io_ExtSerSize,
  348.                and zeroed (with the exeptions as noted)!
  349.        flags         - Must be zero for future compatibility
  350.  
  351.    RESULTS
  352.        D0       - same as io_Error
  353.        io_Error  - If the Open succeded, then io_Error will be null.
  354.                    If the Open failed, then io_Error will be non-zero.
  355.        io_Device - A pointer to whatever device will handle the calls
  356.                    for this unit.  This pointer may be different depending
  357.                    on what unit is requested.
  358.  
  359.    BUGS
  360.     If 7-wire handshaking is specified, a timeout "feature" is enabled.
  361.     If the device holds off the computer for more than about 30-60
  362.     seconds, the device will return the write request with the error
  363.     SerErr_TimerErr.  Don't depend on this, however.  If you want a timeout,
  364.     set up the timer.device and wait for either timer, or serial IO to
  365.     complete.
  366.  
  367.     On open, the serial.device allocates the misc.resource for the
  368.     serial port.  It does not return it until the serial.device is
  369.     expunged from memory.  It should return it when no more openers
  370.     exist.   This code can force a specified device to try and
  371.     expunge.  Of course, if the device is in use nothing will happen:
  372.  
  373.     #include "exec/types.h"
  374.     #include "exec/execbase.h"
  375.     #include "proto/exec.h"
  376.  
  377.     void FlushDevice(char *);
  378.     extern struct ExecBase *SysBase;
  379.  
  380.     void main()
  381.     {
  382.         FlushDevice("serial.device");    /* or parallel.device */
  383.     }
  384.     
  385.     /*
  386.      * Attempts to flush the named device out of memory.
  387.      * If it fails, no status is returned; examination of
  388.      * the problem will reveal that information has no
  389.      * valid use after the Permit().
  390.      */
  391.     void FlushDevice(name)
  392.     char  *name;
  393.     {
  394.     struct Device *result;
  395.  
  396.         Forbid();
  397.         if( result=(struct Device *)FindName(&SysBase->DeviceList,name) )
  398.         RemDevice(result);
  399.         Permit();
  400.     }
  401.  
  402.  
  403.    SEE ALSO
  404.     serial.device/CloseDevice
  405.     serial.device/SDCMD_SETPARAMS
  406.     devices/serial.h
  407.  
  408.  
  409. serial.device/SDCMD_BREAK                             serial.device/SDCMD_BREAK
  410.  
  411.    NAME
  412.        Break -- send a break signal over the serial line
  413.  
  414.    FUNCTION
  415.        This command sends a break signal (serial line held low for an
  416.        extended period) out the serial port. For the built-in port,
  417.        This is accomplished by setting the UARTBRK bit of regisrer ADKCON.
  418.  
  419.        After a duration (user specifiable via setparams, default 250000
  420.        microseconds) the bit is reset and the signal discontinued.
  421.        If the QUEUEDBRK bit of io_SerFlags is set in the io_Request 
  422.        block, the request is placed at the back of the write-request 
  423.        queue and executed in turn. If the QUEUEDBRK bit is not set, 
  424.        the break is started immediately, control returns to the 
  425.        caller, and the timer discontinues the signal after the 
  426.        duration is completed. Be aware that calling BREAK may
  427.     affect other commands such as ABORT, FLUSH, STOP, START, etc...
  428.  
  429.    IO REQUEST
  430.        io_Message      mn_ReplyPort initialized
  431.        io_Device       set by OpenDevice
  432.        io_Unit         set by OpenDevice
  433.        io_Command      SDCMD_BREAK
  434.        io_Flags        set/reset IO_QUICK per above description
  435.  
  436.    RESULTS
  437.        Error -- if the Break succeded, then Error will be null.
  438.            If the Break failed, then the Error will be non-zero.
  439.  
  440.  
  441. serial.device/SDCMD_QUERY                             serial.device/SDCMD_QUERY
  442.  
  443.    NAME
  444.        Query -- query serial port/line status
  445.  
  446.    FUNCTION
  447.        This command return the status of the serial port lines and
  448.        registers. The number of unread bytes in the serial device's
  449.        read buffer is shown in io_Actual.
  450.  
  451.     The break send & received flags are cleared by a query, and
  452.     whenever a read IORequest is returned with a error
  453.     in io_Error.
  454.  
  455.    IO REQUEST
  456.        io_Message      mn_ReplyPort initialized
  457.        io_Device       preset by OpenDevice
  458.        io_Unit         preset by OpenDevice
  459.        io_Command      SDCMD_QUERY
  460.  
  461.    RESULTS
  462.        io_Status        BIT  ACTIVE  FUNCTION
  463.  
  464.               LSB       0    ---    reserved
  465.                         1    ---    reserved
  466.                         2    high   parallel "sel" on the A1000
  467.                                     On the A500 & A2000, "sel" is also
  468.                                     connected to the serial port's
  469.                                     "Ring Indicator".  Be cautious when
  470.                                     making cables.
  471.                         3    low    Data Set Ready
  472.                         4    low    Clear To Send
  473.                         5    low    Carrier Detect
  474.                         6    low    Ready To Send
  475.                         7    low    Data Terminal Ready
  476.               MSB       8    high   hardware overrun
  477.                         9    high   break sent (most recent output)
  478.                        10    high   break received (as latest input)
  479.                        11    high   transmit x-OFFed       
  480.                        12    high   receive x-OFFed       
  481.                     13-15    ---    reserved
  482.  
  483.        io_Actual       set to count of unread input characters
  484.  
  485.        io_Error -- Query will always succeded.
  486.  
  487.  
  488. serial.device/SDCMD_SETPARAMS                     serial.device/SDCMD_SETPARAMS
  489.  
  490.    NAME
  491.        SetParams -- change parameters for the serial port
  492.  
  493.    FUNCTION
  494.        This command allows the caller to change parameters for the
  495.        serial device. Except for xON-xOFF enable/disable, it will
  496.        reject a setparams call if any reads or writes are active 
  497.        or pending. 
  498.           Note specifically:
  499.  
  500.     1. Valid input for io_Baud is between 112 and 292000 baud inclusive;
  501.        asynchronous i/o above 32KB (especially on a busy system) may
  502.        be ambitious.
  503.     2. The EOFMODE and QUEUEDBRK bits of io_SerFlags can be set/reset 
  504.        in the io_Rqst block without a call to SetParams. The SHARED 
  505.        and 7WIRE bits of io_SerFlags can be used in OpenDevice calls.
  506.        ALL OTHER PARAMETERS CAN ONLY BE CHANGED BY THE SetParams 
  507.        COMMAND.
  508.     3. RBufLen must be at least 64.  The buffer may be any multiple of
  509.     64 bytes.
  510.     4. If not used, io_ExtFlags MUST be set to zero.
  511.     5. xON-xOFF is by default enabled. The XDISABLED bit is the only
  512.        parameter that can be changed via a SetParams call while the
  513.        device is active. Note that this will return the value
  514.        SerErr_DevBusy in the io_Error field.
  515.     
  516.     xON/xOFF handshaking is inappropriate for certain binary transfer
  517.     protocalls, such as Xmodem.  The binary data might contain the
  518.     xON (ASCII 17) and xOFF (ASCII 19) characters.
  519.  
  520.     6. If trying to run MIDI, you should set the RAD_BOOGIE bit of
  521.        io_SerFlags to eliminate unneeded overhead. Specifically, this skips
  522.        checks for parity, x-OFF handling, character lengths other than
  523.        8 bits, and testing for a break signal. Setting RAD_BOOGIE will
  524.        also set the XDISABLED bit.
  525.        Note that writing data (that's already in MIDI format) at MIDI rates
  526.        is easily accomplished. Using this driver alone for MIDI reads may,
  527.        however, may not be reliable, due to MIDI timestamping requirements,
  528.        and possibility of overruns in a busy multitasking and/or display
  529.        intensive environment.
  530.     7. If you select mark or space parity (see io_ExtFlags in serial.h),
  531.        this will cause the SERB_PARTY_ON bit to be set, and the setting
  532.        of SERB_PARTY_ODD to be ignored.
  533.     8. For best results, set the RAD_BOOGIE flag whenever possible.  See
  534.     #6 for details.
  535.     9. Note that at this time parity is *not* calculated for the xON-xOFF
  536.     characters.  If you have a system that is picky about the parity of
  537.     these, you must set your own xON-xOFF characters in io_CtlChar.
  538.    10. 7WIRE (CTS/RTS) handshake is bi-directional.  The external side
  539.     is expected to drop CTS several character times before the external
  540.     buffer is full.  The Amiga will drop RTS several character times
  541.     before the Amiga's buffer is full.
  542.  
  543.  
  544.    IO REQUEST
  545.        io_Message      mn_ReplyPort initialized
  546.        io_Device       preset by OpenDevice
  547.        io_Unit         preset by OpenDevice
  548.        io_Command      SDCMD_SETPARAMS (0x0B)
  549.               NOTE that the following fields are filled in by Open 
  550.                        to reflect the serial device's current configuration.
  551.        io_CtlChar      a longword containing byte values for the
  552.                        xON,xOFF,INQ,ACK fields (respectively)
  553.                        (INQ/ACK not used at this time)
  554.        io_RBufLen      length in bytes of input buffer
  555.               NOTE that any change in buffer size causes the
  556.                        current buffer to be deallocated and a new,
  557.                        correctly sized one to be allocated. Thusly,
  558.                        the CONTENTS OF THE OLD BUFFER ARE LOST.
  559.        io_ExtFlags     additional serial flags (bitdefs in devices/serial.h)
  560.             mark & space parity may be specified here.
  561.        io_Baud         baud rate for reads AND writes. (See 1 above)
  562.        io_BrkTime      duration of break signal in MICROseconds
  563.        io_TermArray    ASCII descending-ordered 8-byte array of
  564.                        termination characters. If less than 8 chars
  565.                        used, fill out array w/lowest valid value.
  566.                        Terminators are checked only if EOFMODE bit of
  567.                        io_Serflags is set. (e.g. x512F040303030303 )
  568.        io_ReadLen      number of bits in read word (1-8) not including parity
  569.        io_WriteLen     number of bits in write word (1-8) "      "       "
  570.        io_StopBits     number of stop bits (0, 1 or 2)
  571.        io_SerFlags     see devices/serial.h for bit equates, NOTE that x00
  572.                        yields exclusive access, xON/OFF-enabled, no
  573.                        parity checking, 3-wire protocol and TermArray
  574.                        inactive.
  575.  
  576.    RESULTS
  577.        Error -- if the SetParams succeded, then Error will be null.
  578.            If the SetParams failed, then the Error will be non-zero.
  579.  
  580.    SEE ALSO
  581.     exec/OpenDevice
  582.  
  583.  
  584.